/*
   Copyright 2009 Abdulla Abdurakhmanov (abdulla@latestbit.com)
   Original sources are available at www.latestbit.com

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

package org.latestbit.smartobjects.network;

import java.io.IOException;

/**
 * Base interface for all endpoint coordinator implementations.
 * @author abdulla-a
 *
 */
public interface IEndpointCoordinator {
	public enum ManagedConnectionStatus {
		CONNECTED,
		DISCONNECTED
	}
	
	/**
	 * Gets name of this coordinator
	 * @return coordinator name
	 */
	public String getName();
	
	/**
	 * Gets required connection handler to send some data from available in coordinator
	 * @param managedConnection Managed connection
	 * @return connection handler 
	 * @throws IOException
	 */
	public ConnectionHandler getConnectionHandlerToSend ( IManagedConnection managedConnection )
		throws IOException;

	/**
	 * Event occurs when network connection has been established 
	 * (usually this event occurs when client connected to server).
	 * @param handler connection handler
	 * @return coordinator decision for the managed connection status
	 */
	public ManagedConnectionStatus onConnected(ConnectionHandler handler);
	
	/**
	 * Event occurs when network connection can't be established 
	 * (usually this event occurs when client trying to connect to server).
	 * @param handler connection handler
	 * @param errorMessage Error messages provides by OS
	 * @return coordinator decision for the managed connection status
	 */	
	public ManagedConnectionStatus onConnectionFailure(ConnectionHandler handler, String errorMessage);	
	
	/**
	 * Event occurs when exists connection disconnected
	 * @param handler connection handler
	 * @return coordinator decision for the managed connection status
	 */
	public ManagedConnectionStatus onDisconnected(ConnectionHandler handler);
	
	/**
	 * Event occurs when exists connection removed by bus/application
	 * @param handler connection handler
	 * @return coordinator decision for the managed connection status
	 */	
	public ManagedConnectionStatus onRemoved(ConnectionHandler handler);
	
	/**
	 * Event occurs when coordinator must confirm trying to connect remote side
	 * (usually this event occurs when client trying to connect to server).
	 * @param handler connection handler
	 * @return coordinator decision for the managed connection status
	 */		
	public boolean onRestoreConnectionNeeded(ConnectionHandler handler);

	/**
	 * Initializes coordinator with managed connection factory.
	 * @param factory managed connection factory
	 */
	public void setManagedConnectionFactory(IManagedConnectionFactory factory);
	
	/**
	 * Gets managed connection factory from coordinator
	 * @return managed connection factory
	 */
	public IManagedConnectionFactory getManagedConnectionFactory();
}
